.\" SPDX-License-Identifier: CC-BY-SA-4.0 or-later
.\" SPDX-FileCopyrightText: 2025 grommunio GmbH
.TH mysql_adaptor 4gx "" "Gromox" "Gromox admin reference"
.SH Name
mysql_adaptor \(em MySQL/MariaDB connector for user metadata and authentication
.SH Description
mysql_adaptor is a component for integrating user accounts from
a MySQL/MariaDB database.
.SH Configuration directives
The usual config file location is /etc/gromox/mysql_adaptor.cfg.
.TP
\fBconnection_num\fP
Number of SQL connections to keep active. Note that the SQL server may have
limits in place, such as "max_connections" and "wait_timeout" (cf. `SHOW GLOBAL
VARIABLES LIKE "wait_timeout"`). Automatic reconnection happens by Gromox when
a query is about to be executed.
.br
Default: \fI8\fP
.TP
\fBenable_firsttimepw\fP
This flag determines whether non-LDAP users with no recorded password
(empty users.password SQL column) will have the account's password
set to whatever credential was passed along in the first authentication
request.
.br
Default: \fIno\fP
.TP
\fBmysql_dbname\fP
Default: \fIemail\fP
.TP
\fBmysql_host\fP
The hostname/IP address for contacting the SQL server.
.br
Default: \fIlocalhost\fP
.TP
\fBmysql_password\fP
Default: (unset)
.TP
\fBmysql_port\fP
The TCP port number for contacting the SQL server.
.br
Default: \fI3306\fP
.TP
\fBmysql_rdwr_timeout\fP
This sets the MYSQL_OPT_READ_TIMEOUT and MYSQL_OPT_WRITE_TIMEOUT option values
on the MySQL connection.
.br
Default: \fI0\fP (no timeout)
.TP
\fBmysql_tls_cert\fP
The path name of an optional client public key certificate file for
authentication.
.br
Default: (empty)
.TP
\fBmysql_tls_key\fP
The path name of an optional client private key file for authentication.
.br
Default: (empty)
.TP
\fBmysql_username\fP
Default: \fIroot\fP
.TP
\fBscan_interval\fP
Default: \fI1 minute\fP
.TP
\fBschema_upgrade\fP
This controls what to do when a database schema update is available. Because
the mysql_adaptor component is loaded by many programs across potentially multiple
machines, the basic default is to do nothing.
.RS
.TP
\fBhost:\fP\fIxyz\fP
Perform automatic schema upgrades if the program which has loaded mysql_adaptor
is http(8gx) and only if http.cfg's \fBhost_id\fP value matches \fIxyz\fP.
.TP
(any other value)
No automatic schema upgrades are performed in the process which has loaded the
component. The component may be unable to process or produce certain data, e.g. if it
relies on a table that has not yet been created. Generally, no restart is
needed when that upgrade is finally performed, because SQL queries just start
working. However, there may be some caches, e.g. in the zcore(8gx) address book
that could remain empty until the refresh timer expires or a manual reload is
triggered.
.PP
Default: \fIhost:(system_hostname)\fP
.RE
.SH See also
\fBgromox\fP(7), \fBauthmgr\fP(4gx)
